ParcelAddress API
Australian Address Lookup
Resource URL
UAT:
https://api.uat.nzpost.co.nz/parceladdress/2.0/australia/addresses/{address_id}
Production:
https://api.nzpost.co.nz/parceladdress/2.0/australia/addresses/{address_id}
Resource Description
This resource is intended to be used in conjunction with the Get International Address Detail resource. The Australian Address Lookup returns the detailed information for a single address identifier for an address in Australia. This resource is . The details returned from Google Places is mapped to NZ Post standard address fields. The Australian Address Lookup resource is useful to the merchant who sends a regular volume of parcel to Australian destinations and also consumes the ParcelLabel functionality.
Resource Information
Attribute | Detail |
---|---|
Response Format | JSON |
Requires Authentication | Yes |
Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Please note that all request parameters should be in lower case.
Request Parameters
Field Name | Description | Mand | Example |
---|---|---|---|
address_id | International address identifier used by Google Places. | Yes | EjAzODAwIExhIFBhc2FkYSBBdmUsIExhcyBWZWdhcywgTlYsIFVuaXRlZCBTdGF0ZXM |
Sample Request
https://api.nzpost.co.nz/parceladdress/2.0/australia/addresses/ChIJN1t_tDeuEmsRUsoyG83frY4%26key%3DAIzaSyAC711805j5JJgCpY7RV662jayqffVS-jY
Response Parameters
The following lists the required fields in the Australian Address Lookup response message:
Field Name | Description | Mand | Example |
---|---|---|---|
success | Returns if request is successful | Yes | false |
address | Address object with address details | Y if success = true | "address": {} |
message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Address Object
The following lists the required fields in the address object.
Field Name | Description | Mand | Example |
---|---|---|---|
street_number | The street address number | No | 139 |
street | The name of the street | No | Mitchell St |
suburb | The name of the suburb the address resides | No | Larrakeyah |
state | Name of the Australian state | No | Northern Territory |
state_code | Code for the Australian state | No | NT |
postcode | The postcode associated with the address | No | 0820 |
longitude | The GPS longitude coordinate if the data exists | No | 130.832234 |
latitude | The GPS latitude coordinate if the data exists | No | -12.456088 |
country | The name of the country the address resides | No | Australia |
country_code | The code for the country | No | AU |
formatted_address | The "human readable" address | No | 139 Mitchell St, Larrakeyah NT 0820, Australia |
Error Response Elements
Field Name | Description | Mand | Example |
---|---|---|---|
success | Returns if request is successful | Yes | false |
errors | Error object with error details | Yes if success =false | See Error Object Parameters below |
message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Error Object Parameters
Field Name | Description | Example |
---|---|---|
code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
message | Description of error code | Invalid Parameter(s) |
details | Description of specific error | Address prefix must be at least 4 characters, not including spaces at the beginning or end. |
HTTP Status Codes
Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request
Code | Message |
---|---|
200 | Success |
400 | Bad request |
401 | Unauthorized |
403 | Forbidden |
409 | Invalid request |
500 | System unavailable |
Error Codes
Code | Message |
---|---|
200001 | Partial results returned, not all system(s) have responded |
200002 | All sources responded, data may be incomplete |
400001 | Parameter(s) missing |
400002 | Invalid parameter(s) |
400003 | Non mutually exclusive parameters detected |
401001 | Unauthorised access, please contact administrator |
500001 | General Exception |
500002 | System(s) offline |
Sample Response
Sample success response:
{
"success": true,
"address": {
"street_number": "139",
"street": "Mitchell St",
"suburb": "Larrakeyah",
"state": "Northern Territory",
"state_code": "NT",
"postcode": "0820",
"longitude": 130.832234,
"latitude": -12.456088,
"country": "Australia",
"country_code": "AU",
"formatted_address": "139 Mitchell St, Larrakeyah NT 0820, Australia"
},
"message_id": "27009370-2a69-11e5-a9c0-025c481d35ef"
}
Sample failure responses:
{
"success": false,
"errors": [ {
"code": "40002",
"message": "Invalid Parameter",
"details": "International Address ID is invalid"
}],
"message_id": "ec608f40-2a8b-11e5-a9c0-025c481d35ef"
}
{
"success": false,
"errors": [ {
"code": "40002",
"message": "Invalid Parameter",
"details": "International Address ID is not an Australian Address"
}],
"message_id": "ed0819e0-2a8b-11e5-a9c0-025c481d35ef"
}